home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Arsenal Files 8
/
The Arsenal Files Collection #8 (Arsenal Computer) (1996).ISO
/
gen_bbs
/
inf120x.zip
/
REF.DOC
< prev
next >
Wrap
Text File
|
1996-11-02
|
70KB
|
1,922 lines
______ ___________________ ______
> |____________| InfoMail/386 1.20 |____________| <
~~||~~| Centurion |~~~~~~~~~~~~~~~~~~~| 2:2502/666 |~~||~~
|| ~~~~~~~~~~~~ ~~~~~~~~~~~~ ||
|| ||
|| ||
|| ||
|| CENTURION ||
|| ||
|| ||
|| -*- ||
|| ||
|| ||
|| InfoMail/386 1.20 ||
|| ||
|| A Document Server for Fidonet Systems ||
|| ||
|| Copyright (C) Damian Walker 1996 ||
|| ||
|| ||
|| -*- ||
|| ||
|| ||
|| REFERENCE GUIDE ||
|| ||
|| ||
|| _____ ||
|| (____() ||
|| / / ||
|| / / ||
|| (____() ||
|| _______ ||
|| (_)|||(_) ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| /~~~~~\ ||
|| ~~~~~~~ ||
|| ||
|| ||
|| ||
|| ||
|| ____________ ____________ ||
__||__| Copyright |___________________| 1996 |__||__
> |~~~~~~~~~~~~| (C) Damian Walker |~~~~~~~~~~~~| <
~~~~~~ ~~~~~~~~~~~~~~~~~~~ ~~~~~~
InfoMail/386 1.20 Reference Guide
1. INTRODUCTION
This manual is the Reference Guide to InfoMail/386 1.20. It
contains information about the InfoMail command line, the
individual program components, the fields in the configuration
and document records, a list of macros, and some other
information about the program in reference form.
First time users are recommended to at least scan through the
user guide, which gives step-by-step instructions on how to set
up the program, and also contains some how-to sections on
setting up the more advanced features of the program to deal
with certain common tasks.
Also included in the user guide are introductory information
such as the program's purpose, the system requirements, the
disclaimer, acknowledgements and the version history.
Introduction R- 2
InfoMail/386 1.20 Reference Guide
2. THE COMMAND LINE
The InfoMail command line usage is as follows:
INFOMAIL [<command>] [<switches>]
where <command> is one of the following:
SCAN - Netmail Scan
CONFIG - Configuration Editor
LIST - Document List Editor
UPGRADE - Upgrade Utility
and <switches>, if present, is one or both of the following:
-PATH <path> Path to InfoMail files
-MONO For monochrome users
If no command is supplied, InfoMail displays a brief help screen
which looks similar to this section of the manual.
2.1. The CONFIG command
This loads the full-screen configuration editor. The
configuration editor allows you set up InfoMail's main
configuration parameters (i.e. those not tied to any particular
document). The altered configuration is saved on exit.
2.2. The LIST command
This loads the full-screen document list editor. The document
list editor allows you to add, edit and delete records
describing the individual documents hosted at the system. It
also packs the file (permanently removing deleted records) on
exit.
2.3. The -MONO switch
This is a switch recommended for users of monochrome monitors
(like the author). Although InfoMail's usual colour scheme is
quite visible on a CGA/EGA/VGA monochrome monitor, it could be
better. On Hercules/MDA screens the light blue borders are
displayed with the underline attribute, creating an unattractive
striped display when using the full-screen editors.
The -MONO switch forces InfoMail to use black, grey and white
colours exclusively, in any part of the program: CONFIG, LIST,
SCAN, UPGRADE or the help screen. You can also use it if you
really don't like the author's use of colours.
The Command Line R- 3
InfoMail/386 1.20 Reference Guide
2.4. The -PATH switch
By default, InfoMail will search for its files in the current
directory. If an INFOMAIL environment variable exists, it will
be used to find the files instead (see section 9.2). If the
-PATH switch is present, the parameter following it will be
taken as the path to InfoMail's files, and will override the
INFOMAIL environment variable if it exists.
The parameter after -PATH may be in upper or lower case, and it
may contain DOS-style backslashes (\) or Unix-style forward
slashes (/), or both, if strange-looking filenames take your
fancy. You can add a trailing backslash if you like; InfoMail
will add one internally if you don't.
Use the -PATH switch in conjunction with one of the commands:
CONFIG, LIST, SCAN or UPGRADE. When loading the configuration
editor for the first time, any path supplied will be taken as
the directory for the log file to reside in.
2.5. The SCAN command
This command runs the netmail scan, reading the netmail
directory for incoming netmails addressed to InfoMail and
posting response messages based on them. This is the main part
of InfoMail, and requires that the program is fully configured
before use.
2.6. The UPGRADE command
This is the upgrade utility, which takes the configuration and
document list files of earlier versions of InfoMail and converts
them to a format readable by InfoMail/386 1.20. A backup is
recommended before attempting this operation.
The Command Line R- 4
InfoMail/386 1.20 Reference Guide
3. THE KEYBOARD
This section gives full details of all the keys used throughout
the full-screen components of the InfoMail program. The keys
are mainly self-explanatory, and are displayed at the bottom of
each screen, but this section has been included for completeness
and for reference in the event of ambiguity.
3.1. Editing Text Fields
The following keys are available while editing text fields in
all parts of the InfoMail program.
Left Move cursor left
Right Move cursor right
Home Move cursor to start of line
End Move cursor to end of line
Del Delete character to right of cursor
Backsp Delete character to left of cursor
Enter Accept new field value
Esc Reject new field value (revert to old value)
3.2. The Configuration Editor
The following two sections deal with the keys available in the
various parts of the configuration editor.
3.2.1. Editing the Configuration Record
The following keys are available when editing the configuration
record, i.e. when the configuration record is displayed and one
of the field labels is highlighted.
Up Up one field, or
move to 'AKA List' when on 'Netmail'
Down Down one field, or
move to 'Netmail' when on 'AKA List'
Enter Edit text/numeric field, or
toggle Yes/No field, or
edit AKA list if on AKA List field
Esc Exit and save
3.2.2. Editing the AKA List
After pressing ENTER when the AKA List label is highlighted, a
submenu appears at the bottom of the screen. The following keys
are available at this time.
Ins Add another AKA to the list
Del Remove an AKA from the list
Enter/
Esc Accept the AKA list
The Keyboard R- 5
InfoMail/386 1.20 Reference Guide
After pressing INS or DEL, a valid Fidonet address must be
entered. This means that when deleting, an existing address
must be specified by typing it in manually. There is no menu
bar or other selection mechanism.
3.3. The Document List Editor
The following sections deal with the keys available while in the
document list editor.
3.3.1. Browsing the Document List
Upon first loading the document list editor, the document list
will be displayed. This centres upon a window in which a number
of documents are displayed, one record to a line, and one of the
records will be highlighted. The keys at this point are as
follows:
Up Move up one document
Down Move down one document
Ins Add a new document
Del Toggle delete (X) status of current document
Enter Edit an existing document, or
add a new document if blank record highlighted
Esc Exit and remove records marked as deleted
3.3.2. Editing a Document Record
The keys differ slightly when editing or adding a new document.
When adding a new document, InfoMail will display a completely
blank document record (even the Yes/No fields will be blank) and
ask for a document name. Apart from the normal text editing
keys described in section 3.1, the following keys are available:
Enter Accept name and edit other fields
Esc Abandon document and continue browsing
After accepting a document name or when editing an existing
record, the full document record will be displayed and one of
the field labels will be highlighted. At this point, your keys
are as follows:
Up Up one field, or
move to 'Accesses' when on 'Document'
Down Down one field, or
move to 'Document' when on 'Accesses'
Enter Edit text field, or
toggle Yes/No field, or
toggle Routing between Standard and Smart, or
reset Accesses field to 0, or
edit Status field
Esc Exit to document list and save changes
Note that the 'Document' field cannot be changed, it is constant
once the document name has been initially accepted.
The Keyboard R- 6
InfoMail/386 1.20 Reference Guide
3.3.3. Editing the Message Status
When you select the 'Status' field, its contents should be
highlighted as if it was a text field, but the available keys
are rather different:
C Toggle crash attribute
F Toggle file attribute
H Toggle hold attribute
K Toggle kill attribute
R Toggle freq attribute
U Toggle update attribute
Enter Accept new status
Esc Reject new status, revert to old status
Crash and Hold are mutually exclusive, so when you switch one
on, the other switches off. When switching one off, the other
does not automatically re-appear though. A three-way version of
this relationship exists between File, FReq and Update; when
switching one on the others disappear. Switching one off does
not make either of the others appear. The presence or absence
of Kill does not affect the other attributes.
The Keyboard R- 7
InfoMail/386 1.20 Reference Guide
4. CONFIGURATION FIELDS
This section describes in detail the purpose of each of the
fields in the configuration record, as edited by the
configuration editor.
4.1. Netmail
This is the directory in which your netmail *.MSGs are stored.
It should have a trailing backslash, although InfoMail will add
one for you if you don't put it in yourself. The directory name
will also convert Unix slashes (/) to DOS backslashes (\), and
convert the directory name to upper case.
4.2. Log File
This is the full path and filename to your log file. You can
enter the filename in upper or lower case, and with DOS or Unix
slashes, although InfoMail will convert the name to the normal
DOS standard once you have accepted it.
This field is mandatory. If InfoMail cannot open its log file,
then the netmail scan will refuse to run.
4.3. Active
This is the Active flag, indicating whether the netmail scan
should run. If set to Yes, InfoMail will function normally. If
set to No, InfoMail will refuse to run a netmail scan, although
the other parts of the program will function normally.
This should be used to temporarily inactivate InfoMail (for
maintenance, setup changes or diagnostics) without having to
remove calls to INFOMAIL SCAN from your mailer batch files.
4.4. Max Message Size
This governs the maximum size of an outgoing InfoMail document
message, before addressing information such as TOPT, FMPT and
INTL are added (so leave about 64 bytes for these). If a
document file creates messages above this size, the document
will be posted in a number of smaller messages.
The maximum value for this field is 65535. The minimum value is
1, but setting the maximum message size this low would be rather
stupid.
4.5. Kill Outbound Errors
When set to yes, document lists, file not found errors, document
inactive messages, update accepted/reject messages and search
results will all have the Kill flag added to them. When set to
no, such messages will remain on your system to be dealt with by
you manually, or by another program.
Configuration Fields R- 8
InfoMail/386 1.20 Reference Guide
4.6. Requests
This is the name to which users should post document requests,
and it is recommended that you leave this as 'InfoMail' to
standardise the use of the program. Most existing installations
of the program use this convention.
Case is unimportant in this field; users may post to 'InfoMail',
'INFOMAIL' or 'infomail' and the program will treat the message
as a document request.
4.7. Updates
This is the name to which users should send remote updates to
documents. It is recommended that you leave this as 'InfoMail
Update' in order to standardise the use of the program. The
existing systems which allow remote update and use the name
'InfoMail' for requests follow this convention (they have little
choice, since earlier versions of the program just added the
word 'Update' to the request name to ascertain the update name).
4.8. Searches
This is the name to which users should send document search
messages. It is recommended that you leave this as 'InfoMail
Search' in order to standardise the use of the program. It
cannot, however, be claimed that most existing systems follow
this convention because the document search is a new feature to
InfoMail/386 1.20.
4.9. Kill Inbound Requests/Updates/Searches
These fields signify whether the relevant type of inbound
message will be deleted after processing (if Kill Inbound is set
to 'Yes') or merely marked as 'received' for you or your mail
processing software to deal with (if set to 'No').
4.10. Header and Footer
These fields determine the filenames of the global header and
footer. The header and footer are added to the top and bottom
of each outbound message, i.e. documents and non-document
response messages.
Each field should contain the full DOS path and filename of the
relevant file. If the header field is left blank, then there
will be no header added to outbound messages; a similar rule
follows for the footer field.
4.11. Doc List
This is the text file posted each time a user requests a
document which does not exist, and should be the full DOS path
and filename of a text file. If it is not specified, a
standardised document list is posted to the user.
Configuration Fields R- 9
InfoMail/386 1.20 Reference Guide
4.12. File Err
This is the text file posted to a user when the text file of the
document they have requested is missing. This will most often
happen with documents updated by remote users, if someone
requests the document before the first update message has been
sent. The field should contain the full path and filename of
the text file. If left blank, a standardised message will be
posted to the user.
4.13. Inactive
This is the path and filename of the text file posted to a user
when the document they have requested is marked as inactive. If
it is not specified, a standardised message will be sent in its
stead.
4.14. Accept
This is the path and filename of the text file sent to a user on
successful updating of a remotely-updateable document. A
standardised message will be posted to the user if this field is
not specified.
4.15. Reject
This is the path and filename of the text file sent to a user
when they attempt to request or update a document without
specifying the correct password. It is also sent if a user
specifies a password when requesting a document which is not
passworded, or if the user tries to update a document which does
not have an update password. If this field is left blank, a
standardised message will be posted to the user.
4.16. Results
This is the path and filename of a document search result
template file, sent to the user when a document search is
received. If it is not specified, a standardised search results
message is posted to the user.
4.17. AKA List
This field contains one or more Fidonet addresses, and defines
the AKA's which the system answers to; i.e. your Fidonet
addresses. This field is effectively mandatory, as if you don't
define any addresses then InfoMail will not respond to any
messages.
Configuration Fields R-10
InfoMail/386 1.20 Reference Guide
5. DOCUMENT RECORD FIELDS
This section describes the fields of the document record,
visible when you edit a document in the document list editor.
5.1. Document
This is the document name, or tag. It is the name which a user
must place on the subject line when requesting the document.
Although it is case insensitive, the case is preserved by
InfoMail for output in document lists.
The name cannot contain spaces. Spaces are converted to
underline characters (_) by the upgrade program and the document
list editor, for your convenience. Users requesting a document
must type any underline in the name explicitly on the subject
line of their message, since a space in the subject line
separates a document name from a password.
Note that the only time you can edit a document name is when
adding a new document; InfoMail will ignore you if you try to
select this field on an existing record. Make sure you get the
case right before pressing ENTER to accept the document name!
5.2. Active
This field serves a similar purpose to the field of the same
name in the configuration record; it defines a document as
inactive.
If a user requests a document with the 'Active' flag set to
'No', InfoMail will post a polite refusal instead of the
document text file. An inactive document can be updated
remotely, however. When this field is set to 'Yes', the document
behaves normally.
5.3. Listed
This field defines whether a document will appear in a document
list or not, including a list of matching documents in a
document search result. Only if Listed is set to 'Yes' will a
document appear in such a list, otherwise it will remain hidden.
5.4. Macros
This field defines whether macros in the document text file will
be expanded or not. If set to 'No', left brace characters ('{')
will be treated as any other character, and will remain in the
outgoing document message. If set to 'Yes', InfoMail will
interpret a left brace as the start of a macro sequence, and
attempt to expand it.
Document Record Fields R-11
InfoMail/386 1.20 Reference Guide
Usually this field should be left at 'Yes'. However, sometimes
you may want to post as a document a file which has been
generated by a third-party program, and such a file may contain
brace characters as part of its normal text. In this instance
you should set Macros to 'No' in order to avoid confusion.
5.5. Routing
This field is currently unused, although you can toggle its
value from Standard to Smart. It is there to interface with a
possible future project which will implement routing of InfoMail
documents in a more intelligent way than the simple 'Status'
field or your mailer's routing facilities.
5.6. Subject
This is the subject line for outgoing messages containing the
text of this document. It is normally a more descriptive
version of the document tag, although documents which have File
Attach, File Request or Update Request status should use the
subject line for filenames as per the normal Fidonet standard.
5.7. Status
This field contains some of the attributes for outgoing messages
containing the text of this document. The attributes which
InfoMail supports are Crash, Hold, Update, File, FReq and Kill,
although Pvt and Local are stamped on all outgoing messages as
well.
The Kill flag is relevant to both the primary and secondary
document messages, but the other attributes apply only to the
primary document file. The secondary document message is always
sent routed regardless of the Status field.
5.8. Request
This is the request password. If there is no request password
for a document, then the user must request the document without
a password on the subject line. If a request password is
present, it must be added after the document tag on the subject
line, separated from it by a single space. Password comparisons
are case insensitive.
5.9. Update
This is the remote update password. If there is no remote
update password set for a document, then that document cannot be
updated remotely. If a remote update password is present, then
it must be included on the subject line, after the document
name, in any remote update for the document.
Document Record Fields R-12
InfoMail/386 1.20 Reference Guide
5.10. File
This is the full path and filename of the primary text file for
this document. For normal documents this is the only text file.
On file attaches the text file is usually a covering note for
the file which is attached with the message. This field is
mandatory; without it, InfoMail will post a 'file missing'
message to the user.
5.11. 2nd File
This is the full path and filename of the secondary text file
for this document. Normally it is unused. However, when a
document is set up as a held file attach, it is desirable to
send a second message, routed, to inform the user that a file
attach is waiting. Thus the only message attribute which
secondary messages carry from the Status field is 'Kill'.
5.12. Accesses
This is the document access counter. It cannot be directly
edited, but selecting this field in the document list editor
causes it to reset to zero. Aside from its novelty value as an
in-document macro and its limited informational value, it is
quite useless.
The option to reset it has been provided in the event that you
have requested it when testing your configuration, and want to
reset the counter when you are happy that the document is
correctly set up.
Document Record Fields R-13
InfoMail/386 1.20 Reference Guide
6. DOCUMENT MACROS
InfoMail provides macros which can be embedded in document text
files. These are expanded to provide some meaningful piece of
information each time a message is posted. Such information may
vary from one message to another, which is why it wouldn't be
included verbatim.
Macros are a letter and an integer included in braces ('{' and
'}'), in any order. The integer stands for the minimum length
of the expanded macro, and its range differs for each individual
macro. You could specify the macro {D16} as {16D} or even {1D6}
if it amuses you, and each would expand to a 16-character
document name.
This section provides a list of macros supported by InfoMail,
and explains how to use each one.
6.1. {A} - InfoMail's Address
This macro expands into the current AKA which InfoMail is
operating under. If InfoMail is responding to a message
addressed to 2:2502/666, then the {A} will expand to 2:2502/666
in the outgoing message.
The maximum length of a Fidonet address is 23 characters (up to
4 integers of 5 digits, with a :, / and .), so {A24} and above
create a 23-character address.
6.2. {C} - Access Counter
When embedded in a document, in an error related to a specific
document, or in a header or footer being added to a such a
message, this is the 'Accesses' field from the document list
record. It is increased before being included in the message,
so the first time a document is requested it will be '1'.
When embedded in a search results template, or in a header or
footer added to search results, the {C} expands into the number
of documents matching the search criteria.
When embedded in a document list (as posted when the user
requests a non-existent document) the {C} expands to 0.
The maximum length for the expanded macro is 5 characters. This
is the only macro in which fixed-length expansion is
right-justified, i.e. '{C5}' would expand as ' 23' if the
document had been accessed 23 times.
6.3. {D} - Document Name
This is the document 'tag'. When embedded in a document or a
response associated with a specific document (or a header/footer
attached to such a message), this will expand to the tag of the
relevant document.
Document Macros R-14
InfoMail/386 1.20 Reference Guide
When embedded in a document search template, or a header/footer
attached to such a message, this will expand into the search
criteria entered by the user on the subject line of the inbound
message.
When embedded in a document list, this macro will be expanded
into an empty string. The maximum length of the {D} macro is 16
characters.
6.4. {F} - User's First Name
This expands into the first name of the user, as extracted from
the 'From' field of the inbound message. Thus in response to a
message from 'Damian Walker', the {F} macro would expand as
'Damian'. The maximum length of this macro is 35 characters.
6.5. {I} - InfoMail Request Name
This is the request name as set up in the configuration editor.
It can be embedded in instructions on how to request other
documents, or in a welcoming sentence such as 'thank you for
writing to {I}'. The maximum length is 35 characters.
6.6. {L} - User's Last Name
This expands into the user's last name, as extracted from the
incoming message. Thus in a response to a message from 'Damian
Walker', {L} would expand into 'Walker', and in a response to
'NetMgr 0.99' {L} would be '0.99'. Be careful of adding {F} and
{L} together to create the user's full name; some users include
their middle name or initial, and some users include suffixes
such as 'Jr' or 'III' to their names. The {L} macro isn't as
useful as it seems at first. Maximum length is 35 characters.
6.7. {N} - User's Full Name
This expands into the full name of the user to whom the response
is being posted, exactly as extracted from the 'From' field of
the inbound message. The maximum length is 35 characters.
6.8. {O} - Operating System Filename of Document
When embedded in a document, a document-related error or a
header/footer attached to such a message, {O} returns the full
filename of the document being requested. On other messages,
{O} expands to a blank string. Maximum length is 64 characters.
6.9. {P} - Program Name and Version
This macro allows you to impress users with your impeccable
taste for document server software by telling them that you are
running InfoMail/386 1.20. In InfoMail 1.11 it expands to
'InfoMail 1.11' and in later versions of InfoMail, the later
program ID will be returned. The maximum formatted length is 35
characters.
Document Macros R-15
InfoMail/386 1.20 Reference Guide
6.10. {S} - Document Subject Line
This allows you to embed the subject line of the document. It
is included only for completeness, since the user can see the
subject line plainly in their message editor.
When embedded into response messages other than documents, {S}
will expand into the subject line of the error message being
posted, making it equally useless in this type of message. The
maximum formatted length is 71 characters.
6.11. {U} - User's Address
This expands into the address of the user to whom the current
message is being posted in reply. The maximum length of the
formatted macro is 23 characters.
6.12. {W} - Document List
Usually this macro expands out into an entire list of all
document tags set up on the system. These are formatted four to
a line, right-justified as per the author's preference (and
nobody's complained about this up to now). Any formatted length
included in the macro will be ignored since the list is not
suitable for inclusion as a field in a formatted table.
The usual use of this macro is as embedded in a document list
response message, or in a specially created document list set up
as a document in itself.
It is also used in a document search results template, and
decides the position and format of the list of documents.
Obviously, in a search results message the {W} will expand into
a list of only documents which match the search criteria, rather
than a full document list as happens when it is included
elsewhere.
6.13. {X} - Extended Document List
This macro behaves in a similar fashion to the {W} macro, except
that the document listing includes subject lines, and is
formatted with one document per line instead of four. Again,
the formatted length, if included, is ignored.
As with the {W} macro, when included in a document search
results template, only the documents matching the search
criteria will be included in the list.
6.14. {{} - Literal Left Brace
This macro provides a way to represent the '{' character in
outgoing documents. Some sample C code could be represented as
follows:
Document Macros R-16
InfoMail/386 1.20 Reference Guide
void main(void)
{{}
printf("Hello World\n");
}
which would be expanded into the following output text:
void main(void)
{
printf("Hello World\n");
}
Document Macros R-17
InfoMail/386 1.20 Reference Guide
7. SCREEN MESSAGES
This section is a reference of all the messages which appear on
the screen, and in the case of error messages, what to do about
them.
7.1. ! Cannot create configuration file
This message indicates that the configuration editor cannot
create the initial configuration file, INFOMAIL.CFG. This is
usually a path error, for instance, trying to create a
configuration file in a non-existent directory or a
non-writeable drive.
7.2. ! Cannot create document list file
This message indicates that the document list editor cannot
create the initial document list files, INFOMAIL.DAT and
INFOMAIL.NDX. This is usually a path error, for instance,
trying to create a document list file in a non-existent
directory or a non-writeable drive.
Very occasionally, this error may arise as a result of a disk or
network fault, or some other low level problem. If this is the
case, check that the DAT file is not present before loading the
configuration editor again (it may be that the DAT file could be
created but not the NDX-- having a DAT without an NDX is no use
to InfoMail).
7.3. ! Cannot open configuration file
This error message is given by the netmail scan. It indicates
that it cannot open the file INFOMAIL.CFG.
This may arise because the file is not there, i.e. you haven't
loaded the configuration editor before attempting a netmail scan
for the first time. In this case, you'll have to load the
configuration editor as described in the user guide, followed by
the document list editor to prevent the error described in
section 7.4 of this manual.
It may also arise when InfoMail cannot find its files. For
instance, you're running InfoMail outside its own directory with
no -PATH switch or INFOMAIL environment variable. The
solution-- run InfoMail from its own directory, set the INFOMAIL
environment variable or use the -PATH switch.
The error may also be displayed if the INFOMAIL.CFG is invalid;
this could be because of corruption or because you haven't yet
upgraded the files from a previous installation of an older
version of InfoMail before attempting a netmail scan.
Error Messages R-18
InfoMail/386 1.20 Reference Guide
7.4. ! Cannot open document list file
This error is given by the netmail scan if for some reason it
cannot open the document list file (INFOMAIL.DAT) and its index
file (INFOMAIL.NDX).
This may arise because the files don't yet exist, if you have
run the netmail scan before the document list editor. In this
case, the solution is simple-- run the document list editor to
create the files!
It may arise because you haven't indicated to InfoMail where the
files are. To solve this, make sure that (a) you are in
InfoMail's directory before running, (b) you have use the -PATH
parameter to point InfoMail to its files, or (c) the INFOMAIL
environment variable is set correctly.
It could also arise if the files are invalid, such as when
corruption occurs or when you try and run InfoMail/386 1.20 when
using old data files from an earlier version.
7.5. ! Cannot open log file
This error is issued by the netmail scan when it cannot open the
log file for output. This will usually be because the log file
has not been defined correctly in the configuration editor; to
fix this, make sure that the log file is a valid path and
filename to a writeable DOS drive and directory.
7.6. ! Cannot read netmail directory
This error is issued when the netmail scan failed to find the
netmail directory. This would usually be because the netmail
directory has been incorrectly defined in the configuration
editor; ensure that the netmail directory in InfoMail matches
that of your mailer or mail processor. Ensure also that you are
actually using a *.MSG netmail area rather than JAM, Hudson or
Squish (none of which InfoMail can read).
7.7. ? Cannot read netmail message
This occurs when InfoMail has trouble reading a netmail message
which is known to exist. It will usually be a file sharing
violation or, in unfortunate cases, corruption of a netmail
file.
In the case of a sharing violation, a later run of the InfoMail
scan will probably pick up the offending netmail and process it
then, as long as whatever program had the message file open in
the first instance has closed the file since.
In the case of file corruption, you will have to remove the
offending netmail message.
Error Messages R-19
InfoMail/386 1.20 Reference Guide
In no instance is this a fatal error, if InfoMail cannot read
one netmail message it will ignore it and progress to the next
message.
7.8. * Conversion finished
This simply indicates that the UPGRADE process has run
successfully and the files from your installation of an earlier
version of InfoMail have been converted to a format InfoMail/386
1.20 can read.
Note that the original files are available in case a restoration
of the previous InfoMail version is needed; these are named
INFOMAIL.CF$ and INFOMAIL.DA$ (there is no INFOMAIL.ND$ since
earlier versions of InfoMail had no document file index).
7.9. * Converting configuration file
This indicates that the old configuration file has been
successfully read and is now being converted to InfoMail/386
1.20 format.
7.10. * Converting document list file
This indicates that the old document list file has been
successfully opened and is now being converted to InfoMail/386
1.20 format.
7.11. Error: InfoMail is already running
This error occurs mostly in multitasking environments, where
there is a possibility of InfoMail being run simultaneously in
multiple DOS sessions. It indicates that InfoMail might already
be running elsewhere.
The error could also be caused if InfoMail has crashed on a
previous run, leaving its semaphore file behind. The semaphore
file is named INFOMAIL.SEM and it is located in InfoMail's
directory as defined by the -PATH switch or the INFOMAIL
environment variable. This may be removed if you are sure that
InfoMail is not running elsewhere.
Creating the semaphore file manually will also result in this
message being displayed when you try to run InfoMail; try it out
if such things amuse you.
7.12. Error: cannot create semaphore
This indicates that there was an error creating the semaphore
file which InfoMail tries to drop as soon as it is run.
Error Messages R-20
InfoMail/386 1.20 Reference Guide
The most probable cause is that the path to InfoMail's files has
not been correctly specified, and is pointing to a non-existent
directory or a non-writeable device. In this case, correct the
setting of the INFOMAIL environment variable or the parameter of
the -PATH command you use to invoke InfoMail.
7.13. Error: cannot remove semaphore
This error occurs when InfoMail cannot delete its own semaphore.
You can cause this error yourself in a multitasking environment
by deleting the semaphore file in one window while InfoMail is
running in another. When InfoMail exits it then issues this
error.
In another instance, the error might be caused by a sharing
violation or other file-system related error. In this case,
ensure that the semaphore file has been deleted manually before
attempting to run InfoMail again.
7.14. Error: type INFOMAIL alone for help
This is a simple command line error. It results when you
misspell a command word or switch, use the -PATH switch with
nothing after it, or type complete nonsense. To solve it,
simply check your command line and correct the error or, as the
prompt says, type INFOMAIL on its own for a concise help screen.
7.15. * Finished!
A simple message indicating that InfoMail has finished the
netmail scan. This should be the last thing you see after
the netmail scan has been run (apart from a 'cannot remove
semaphore' error perhaps).
7.16. ! Invalid configuration file
This error is output by the configuration editor if a file is
present but cannot be loaded. This is usually caused by running
INFOMAIL CONFIG with data files from an earlier version of
InfoMail-- in this case run INFOMAIL UPGRADE before attempting
to load the configuration editor.
At other times it occurs because of file corruption, or when you
have mistakenly copied a nonsense file over INFOMAIL.CFG. In
the event of minor file corruption (a byte here or there), you
can make partial corrections by ensuring the first 8 bytes of
the configuration file read "INF120S"<NUL> where <NUL> is an
ASCII zero. You would use a hex editor for this, not a text
editor.
In the event of irrepairable file corruption or copying other
files over INFOMAIL.CFG the only solution is to use your latest
backup of the INFOMAIL.CFG file, copying it over the damaged
version of the file. If you haven't taken a backup, what a
shame.
Error Messages R-21
InfoMail/386 1.20 Reference Guide
7.17. ! Invalid document list file
This is issued by the document list editor when an existing
document list file or index file is corrupted or invalid. It
most often occurs when running the list editor on a data file
from an earlier version of InfoMail. In this case you must
run the INFOMAIL UPGRADE procedure before attempting to edit
documents.
Other causes, as for the error described in section 7.16, are
file corruption or overwriting of INFOMAIL.DAT and/or
INFOMAIL.NDX with nonsense files. In the event of minor file
corruption, it is not recommended that you attempt to restore
these files with a hex editor, as errors here may show odd
behaviour by the document list editor. Restore the files from
your latest backup instead.
7.18. ! Missing or invalid configuration file
This is a general error issued by the upgrade utility if it
cannot find a valid configuration file from InfoMail 1.00 or
InfoMail 1.10/1.11.
To correct this, ensure that the files are in the InfoMail
directory, i.e. where you would expect the new files to appear,
before running the upgrade process. Remember to point InfoMail
to these files using -PATH or the INFOMAIL environment variable,
or alteratively, run INFOMAIL UPGRADE from InfoMail's own
directory.
7.19. ! Missing or invalid document list file
This error occurs when the InfoMail upgrade utility cannot find
a valid document list file from version 1.00 or 1.10/1.11 to
upgrade. See section 7.18 for details of how to deal with this
error.
7.20. ! No netmails to read
This appears when there are no *.MSGs at all in the designated
netmail directory. If there are messages in the netmail
directory not addressed to InfoMail, this message should not
appear.
If you see this message when first installing and testing
InfoMail, check that the 'Netmail' field is correctly set up in
the configuration editor.
7.21. * Processing request from...
This message simply lets you know that InfoMail has found a
document request, if you happen to be watching a netmail scan go
by. It can be a useful diagnostic shortcut, allowing you to see
that a test request was received and processed without having to
load your message editor again.
Error Messages R-22
InfoMail/386 1.20 Reference Guide
7.22. * Processing search from...
This message appears whenever InfoMail processes a document
search message found in the netmail directory.
7.23. * Processing update from...
This message appears whenever InfoMail processes a document
update message found in the netmail directory. Details of
acceptance of rejection of the update are not displayed but may
be found in the log file (see section 8).
Error Messages R-23
InfoMail/386 1.20 Reference Guide
8. LOG FILE ENTRIES
This section deals with the various entries you may find upon
examination of the log file. Only the netmail scan process
writes to the log file, it being assumed that you are usually
present at the keyboard to witness the activities of the other
program components such as the configuration editor.
The log file is similar in layout to that produced by some other
software, such as FrontDoor and GEcho. It is suitable for
inclusion in compound log files if you like to keep the logs of
all your software that way. Each netmail scan initialises by
writing the following to the log file:
<blank line>
---------- InfoMail/386 1.20, DD-Mmm-YY
where DD-Mmm-YY is the current date. Each individual log entry
has the following format:
X HH:MM:YY <actual log entry text>
where X is one of the following:
! for fatal errors causing an immediate exit
? for errors from which InfoMail can recover
* for major log messages (message found, etc).
+ for minor messages such as file/message writes
- for trivial log messages
and HH:MM:YY is the time of the log stamp. The actual log entry
text is freeform, and varies according to each event logged.
Where a log file message has the same meaning and solution as an
identical screen message, you are referred to the screen
message's entry in section 7 (to avoid repetition of the same
text in this manual).
8.1. ? Cannot open document file...
This warning is written to the log file when InfoMail cannot
open the document text file of a specific document. The log
file includes details of the document to allow you to check your
setup.
Usually this warning occurs because a document's filename is
incorrectly specified in the document list editor; to correct
this problem you should check the document entry in the document
list editor.
Occasionally this warning may occur due to sharing violation
errors or file system corruption. It is not a fatal error;
InfoMail should inform the user of the problem and continue to
process other messages.
Log File Entries R-24
InfoMail/386 1.20 Reference Guide
8.2. ! Cannot read netmail directory
This indicates that the netmail directory could not be found,
refer to section 7.6 for tips on how to deal with this fatal
error.
8.3. ? Cannot read netmail message
This indicates that InfoMail had trouble reading an existing
netmail message. Refer to section 7.7 for tips on how to deal
with this. This is a warning rather than a fatal error, so
InfoMail continues to process later messages.
8.4. ? Cannot write netmail message
This error appears when InfoMail could not write a netmail
message. This will usually happen due to sharing violation or
file system errors. It will follow a 'Processing
request/update/search from...' log entry; check the name and
address in that message and (if you don't kill them) inbound
messages to get details of what the user wanted if you wish to
get in touch with the user afterwards.
In the case of sharing violations, the best way to avoid this
error is to ensure that no other application is reading/writing
to the netmail directory when InfoMail is processing messages.
Many programs allow semaphores to be used for this purpose.
8.5. - Document list closed
This signifies (surprise) that the document list file has been
closed, and is used along with the log entry described in
section 8.6 to indicate the successful loading/exiting of
InfoMail.
8.6. - Document list opened
This shows that the document list has been opened successfully.
If InfoMail has managed to get this far, it is a fair indication
that initialisation has been fully successful, i.e. InfoMail's
directory, all the configuration files, the log file and the
netmail directory have all been initialised. When there are no
inbound messages addressed to InfoMail, a normal log entry
should read something like this:
---------- InfoMail/386 1.20, 27-Oct-96
- 10:01:58 Document list opened
- 10:01:59 Document list closed
8.7. ! Missing or invalid document list
This fatal error indicates that the document list could not be
loaded, and is identical to the 'Cannot open document list'
screen error message described in section 7.4.
Log File Entries R-25
InfoMail/386 1.20 Reference Guide
8.8. ! No netmails to read
This 'error' is written when the netmail directory is completely
empty, and co-incides in occurrence and exact meaning with its
associated screen message, described in section 7.20.
8.9. * Processing request from...
This is written when a document request is recieved and
processed. The log line includes the name and address of the
remote user.
8.10. * Processing search from...
This message is written when a document search message is
encountered. It gives the name and address of the remote user
who posted the search.
8.11. * Processing update from...
This entry occurs when InfoMail receives a document update from
a remote user, whose name and address are included in the entry.
8.12. + Sending document list to...
This entry indicates that the document list is being sent to the
remote user; this user should be the same user identified in the
'Processing ... from ...' entry immediately above in the log
file.
When you see this entry, you know that the user has requested
(or attempted to update) a document which does not exist. If
you want to see which document, you will have to look at the
inbound request, assuming that you keep those requests.
8.13. + Sending document...
This entry shows that a document has been sent to the user in
response to a document request. The entry includes details of
the user and the document, so you can keep track of which
documents are being requested and who is requesting them.
8.14. + Sending file error to...
This message, occurring after a '? Cannot open document file'
error, shows that the user has been informed that the document
file cannot be found.
Log File Entries R-26
InfoMail/386 1.20 Reference Guide
8.15. + Sending inactive document error to...
This log entry indicates that the user has been informed that
the document they requested is inactive. The document details
are not included here, you will have to look at inbound messages
to see the document requested. Alternatively, check the
document list editor for inactive documents if you don't think
you should have any.
8.16. + Sending reject message to...
When a document request or update is rejected, this log entry
shows that the user has been sent the 'update/request rejected'
standard message.
8.17. + Sending search results to...
This log entry shows that the results of a user's search have
been posted to them, and follows a 'Processing search from...'
log entry.
8.18. + Sending update confirmation to...
When a user successfully updates a document, they receive a
confirmation message. This log entry shows that the
confirmation message has been sent to them.
8.19. + Updated document...
Coinciding with the log entry described in section 8.18, this
entry shows that the updated document text has been written to
the document file. Document details are provided here.
Log File Entries R-27
InfoMail/386 1.20 Reference Guide
9. MISCELLANEOUS INFORMATION
This section contains anything which is important enough to
include for reference, but which isn't relevant to any of the
other sections of this reference guide.
9.1. InfoMail Directory Contents
This subsection describes all the files which should be present
in the InfoMail directory, including all those from the original
archive and others created by InfoMail.
9.1.1 INFOMAIL.EXE - The InfoMail Executable
This is the main executable for InfoMail/386 1.20, including all
of the program components.
9.1.2. CWSDPMI.EXE - The DPMI Server
CWSDPMI is the DPMI server supplied with InfoMail/386 1.20. It
was written by Charles Sandmann especially for DJGPP and
programs written using that compiler.
You can get the latest version of CWSDPMI on the Internet at
www.delorie.com. InfoMail's author will attempt to keep up to
date with the latest release of this DPMI server and keep a copy
at Centurion for file request. At the time of writing,
CSDPMI3B.ARJ is available for file request at 2:2502/666 (note
no W in the archive name).
If your operating system does not provide its own DPMI server
for DOS sessions then you can use CWSDPMI instead. Simply move
or copy CWSDPMI.EXE to somewhere on your DOS path and InfoMail
will automatically find and load it each time you run
INFOMAIL.EXE.
9.1.3. *.DOC - The Main Documentation
The files CONTENTS.DOC, USER.DOC, REF.DOC, DEV.DOC and INDEX.DOC
all form the main documentation.
CONTENTS.DOC is the table of contents for all file .DOC files,
and contains full information on all sections of them.
USER.DOC is the user guide, intended as a starting place for
first-time InfoMail users and those who want a 'how-to' answer
to some common problems and features.
You are reading REF.DOC.
DEV.DOC is the developer's guide, intended for those who want to
write programs to interface with InfoMail.
INDEX.DOC is the full alphabetic index for all the other major
document files.
Miscellaneous Information R-28
InfoMail/386 1.20 Reference Guide
9.1.4. FILE_ID.DIZ/*.TXT - Minor Documentation Files
These files include such things as the long file description,
the quick start guide and the 'what's new' document. Filenames
may vary; see the actual archive for a full list.
9.1.5. *.SAM - The Sample Files
These files are samples created for your conveniece. Some of
them are intended for use with the tutorial in the user guide,
and others are for general use.
DOCUMENT.SAM is the sample document file mentioned in the
tutorial, and has no other use apart from a quick document for
any testing you want to do.
HEADER.SAM and FOOTER.SAM are the sample header and footer
files. If these are to your taste, you can use these directly
by specifying their names in the relevant fields of the
configuration editor.
DOCLIST.SAM is a sample document list file. It is identical to
the internal document list sent as a default, so including its
name directly in your configuration file won't appear to do
much. It is included as a starting point for you to create your
own customised document list.
FILEERR.SAM is the sample 'file not found' error message
template. It is identical to the internal message of the same
purpose, but can be taken as a starting point for a customised
version of this message.
INACTIVE.SAM is the sample 'document inactive' message,
identical in appearance to the internal version but usable as a
starting point for customisation.
ACCEPT.SAM and REJECT.SAM are the 'update accepted' and 'update
or request rejected' templates. As with FILEERR.SAM and
INACTIVE.SAM, these are identical to the default messages of
that purpose but can be used to create customised messages more
to your taste.
RESULTS.SAM is the sample document results template. Again,
this is identical to the internal version. It is recommended
that document search results list the subject line of documents
if the names aren't that descriptive. If you wish to follow
this recommendation you can simply change the {W} in this text
file to an {X} (see section 6 about macros), include the full
path and filename of RESULTS.SAM in your configuration (in the
'Results' field), try out a document search and inspect the
results.
Miscellaneous Information R-29
InfoMail/386 1.20 Reference Guide
9.1.6. INFOMAIL.CFG - The Configuration File
This is the file created by INFOMAIL CONFIG or INFOMAIL UPGRADE
when you first install the package, and it is used (and
required) by every other part of the program.
9.1.7. INFOMAIL.DAT/INFOMAIL.NDX - The Document List
INFOMAIL.DAT is the document list file, containing all the
details of all the documents. It is created by the document
list editor or the upgrade utility, and is used by the netmail
scan.
INFOMAIL.NDX is the index file, used by the document list editor
to ensure that the documents are in alphabetical order, and by
the netmail scan to speed up location of individual documents
and to keep document lists and searches in order. It is created
by the upgrade utility or document list editor, and is mandatory
for the running of the program.
9.1.8. INFOMAIL.CF$/INFOMAIL.DA$ - Upgrade Backups
These files are created by the UPGRADE process, and are simply
copies of your previous configuration files. These are useful
if you need to revert to an earlier version of InfoMail for some
reason, or if you make a mess of your configuration and need to
re-import the original files.
When you are satisfied that InfoMail is set up correctly you may
delete these files. It is recommended that you let InfoMail run
for a while beforehand, in case errors appear which are not
initially apparent.
9.2. The INFOMAIL Environment Variable
This is a convenient way of indicating to InfoMail where its
data files are, it is the standard practice adopted by a large
number of Fidonet applications and utilities. As an example,
SET INFOMAIL=C:\INFOMAIL\
tells InfoMail that its data files are in C:\INFOMAIL. The
trailing backslash is not necessary; InfoMail adds it internally
if it is not present.
The environment variable is overridden by the -PATH switch on
the InfoMail command line; it is usual to use one or the other,
but not both.
9.3. Defaults
These are the default values of the fields in the configuration
editor. They are used when setting up InfoMail for the first
time. When upgrading, all the fields present in the earlier
version of InfoMail retain their existing values.
Miscellaneous Information R-30
InfoMail/386 1.20 Reference Guide
Netmail .\
Log file <path>\INFOMAIL.LOG
Active Yes
Max Msg Size 16384
Kill Outbound Yes
Requests InfoMail
Updates InfoMail Update
Searches InfoMail Search
Kill Requests Yes
Kill Updates Yes
Kill Searches Yes
Header <empty>
Footer <empty>
Doc list <empty>
File err <empty>
Inactive <empty>
Accept <empty>
Reject <empty>
Results <empty>
AKA List <empty>
<path> is the path as specified in the INFOMAIL environment
variable or the -PATH command line switch; if neither are used
it defaults to '.\' and really ought to be changed. When adding
a new document, the default values are as follows:
Document <always entered by user>
Active Yes
Listed Yes
Macros Yes <see below>
Routing Standard
Subject <empty>
Status <empty>
Request <empty>
Update <empty>
File <empty>
2nd File <empty>
Accesses 0
When upgrading from a previous version of InfoMail, the fields
present in that version retain their existing values. When
upgrading from InfoMail 1.00, the Macros field in all documents
is initially set to 'No' in order to make the new installation
behave like the old one (there may be documents containing '{'
and '}' which would cause confusion with Macros set to 'Yes).
9.4. Limits
These are the limits placed on various fields and other parts of
InfoMail (length of text fields is readily apparent from the
screen display, so is not listed here)
Miscellaneous Information R-31
InfoMail/386 1.20 Reference Guide
Max Msg Size 65535
AKA List As many addresses as memory will hold
Accesses 65535 (then resets to 0)
Max Doc Size 64k after macro expansion
Documents 2 billion
Miscellaneous Information R-32
